<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>report.pl - generate Broadband Forum USP and CWMP data model reports</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:_securityagent@osx382.sd.apple.com" />
</head>

<body>



<ul id="index">
  <li><a href="#NAME">NAME</a></li>
  <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
  <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
  <li><a href="#OPTIONS">OPTIONS</a></li>
  <li><a href="#LIMITATIONS">LIMITATIONS</a></li>
</ul>

<h1 id="NAME">NAME</h1>

<p>report.pl - generate Broadband Forum USP and CWMP data model reports</p>

<h1 id="SYNOPSIS">SYNOPSIS</h1>

<p><b>report.pl</b> [--allbibrefs] [--alldatatypes] [--altnotifreqstyle] [--autobase] [--autodatatype] [--automodel] [--bibrefdocfirst] [--canonical] [--catalog=s]... [--clampversion=s]... [--commandcolor=s]... [--compare] [--components] [--configfile=s(&quot;&quot;)] [--cwmpindex=s(..)] [--cwmppath=s(cwmp)] [--debugpath=p(&quot;&quot;)] [--deletedeprecated] [--diffs] [--diffsext=s(diffs)]... [--dtprofile=s]... [--dtspec[=s]] [--dtuuid[=s]] [--exitcode] [--help] [--ignore=p(&quot;&quot;)] [--ignoreenableparameter] [--immutablenonfunctionalkeys] [--importsuffix=s(&quot;&quot;)] [--include=d]... [--info] [--lastonly] [--loglevel=tn(i)] [--logoalt=s()] [--logoref=s()] [--logosrc=s()] [--markmounttype] [--marktemplates] [--maxchardiffs=i(5)] [--maxworddiffs=i(10)] [--noautomodel] [--nocomments] [--nofontstyles] [--nohyphenate] [--nolinks] [--nologprefix] [--nomodels] [--noobjects] [--noparameters] [--noprofiles] [--noshowreadonly] [--notemplates] [--nowarnbibref] [--nowarnenableparameter] [--nowarnnumentries] [--nowarnredef] [--nowarnreport] [--nowarnprofbadref] [--nowarnstaticdefault] [--nowarnuniquekeys] [--nowarnwtref] [--noxmllink] [--objpat=p(&quot;&quot;)] [--option=n=v]... [--outfile=s] [--pedantic[=i(1)]] [--plugindir=d]... [--plugin=s]... [--quiet] [--report=html|htmlbbf|(null)|tab|text|xls|xml|xsd|other...] [--showdiffs] [--showreadonly] [--showspec] [--showsyntax] [--showunion] [--sortobjects] [--special=s] [--thisonly] [--tr106=s(TR-106)] [--trpage=s(https://www.broadband-forum.org/technical/download)] [--ucprofile=s]... [--ugly] [--upnpdm] [--usp] [--verbose[=i(1)]] [--version] [--warnbibref[=i(1)]] [--writonly] [--xmllinelength=i(79)] DM-instance...</p>

<ul>

<li><p>the most common options are --include, --loglevel and --report=html</p>

</li>
<li><p>use --compare to compare files and --diffs to show differences</p>

</li>
<li><p>cannot specify both --report and --special</p>

</li>
</ul>

<h1 id="DESCRIPTION">DESCRIPTION</h1>

<p>The files specified on the command line are assumed to be XML TR-069 data model definitions compliant with the <i>cwmp:datamodel</i> (DM) XML schema.</p>

<p>The script parses, validates and reports on these files, generating output in various possible formats to <i>stdout</i>.</p>

<p>There are a large number of options but in practice only a few need to be used. For example:</p>

<p>./report.pl --report html tr-098-1-2-0.xml &gt;tr-098-1-2-0.html</p>

<h1 id="OPTIONS">OPTIONS</h1>

<dl>

<dt id="allbibrefs"><b>--allbibrefs</b></dt>
<dd>

<p>usually only bibliographic references that are referenced from within the data model definition are listed in the report; this isn&#39;t much help when generating a list of bibliographic references without a data model! that&#39;s what this option is for; currently it affects only <b>html</b> reports</p>

<p>see also <b>--alldatatypes</b></p>

</dd>
<dt id="alldatatypes"><b>--alldatatypes</b></dt>
<dd>

<p>usually only data types that are referenced from within the data model definition are listed in the report; this isn&#39;t much help when generating a list of data types without a data model! that&#39;s what this option is for; currently it affects only <b>html</b> reports</p>

<p>see also <b>--allbibrefs</b></p>

</dd>
<dt id="altnotifreqstyle"><b>--altnotifreqstyle</b></dt>
<dd>

<p>enables an &quot;alternative notification requirements style&quot; that affects the HTML report&#39;s &quot;Inform and Notification Requirements&quot; section; when enabled, this section is called &quot;Notification Requirements&quot; and contains only a &quot;Parameters for which Value Change Notification MAY be Denied&quot; section</p>

<p>note: use of this option is appropriate when generating reports for data models that will be used with USP; the <b>--usp</b> option enables it automatically</p>

</dd>
<dt id="autobase"><b>--autobase</b></dt>
<dd>

<p>causes automatic addition of <b>base</b> attributes when models, parameters and objects are re-defined, and suppression of redefinition warnings (useful when processing auto-generated data model definitions)</p>

<p>is implied by <b>--compare</b></p>

</dd>
<dt id="automodel"><b>--automodel</b></dt>
<dd>

<p>enables the auto-generation, if no <b>model</b> element was encountered, of an auto-generated model that references each non-internal component, i.e. each component whose name doesn&#39;t begin with an underscore</p>

<p>this is preferable to the (deprecated) <b>--noautomodel</b> because it allows various error messages to be suppressed</p>

</dd>
<dt id="autodatatype"><b>--autodatatype</b></dt>
<dd>

<p>causes the <b>{{datatype}}</b> template to be automatically prefixed for parameters with named data types</p>

<p>this is deprecated because it is enabled by default</p>

</dd>
<dt id="bibrefdocfirst"><b>--bibrefdocfirst</b></dt>
<dd>

<p>causes the <b>{{bibref}}</b> template to be expanded with the document first, i.e. <b>[DOC] Section n</b> rather than the default of <b>Section n/[DOC]</b></p>

</dd>
<dt id="canonical"><b>--canonical</b></dt>
<dd>

<p>new behavior: omits text that would cause lots of differences between nominally similar reports; is particularly aimed at allowing direct comparison of HTML generated from normative XML and from the &quot;flattened&quot; XML of the <b>xml</b> report</p>

<p>old behavior: affected only the <b>xml</b> report; caused descriptions to be processed into a canonical form that eased comparison with the original Microsoft Word descriptions</p>

</dd>
<dt id="catalog-s"><b>--catalog=s</b>...</dt>
<dd>

<p>can be specified multiple times; XML catalogs (https://en.wikipedia.org/wiki/XML_Catalog); the current directory and any directories specified via <b>--include</b> are searched when locating XML catalogs</p>

<p>XML catalogs are used only when processing URL-valued <b>schemaLocation</b> attributes during DM instance validation; it is not necessary to use XML catalogs in order to validate DM instances; see <b>--loglevel</b></p>

</dd>
<dt id="clampversion-s"><b>--clampversion=s</b>...</dt>
<dd>

<p>sets the &quot;clamp version&quot;, which should be a version string of the form &quot;major.minor&quot; or &quot;major.minor.patch&quot;</p>

<p>any versions, e.g. parameter or object versions, that are less than the clamp version will be clamped (i.e. set to) the clamp version; this is useful (for example) for avoiding warnings when including a component that contains parameters or objects that were defined before the parent entity was defined</p>

<p>note: this option is only used when it&#39;s a valid version of the current data model; if not, it will be quietly ignored</p>

<p>note: the <b>--usp</b> option enables this option automatically (with the value &quot;2.12&quot;)</p>

</dd>
<dt id="commandcolor-s"><b>--commandcolor=s</b>...</dt>
<dd>

<p>sets the background colors to be used (in the HTML report) for commands and events; can be specified up to four times to set (in order) the background colors for:</p>

<ul>

<li><p>commands and events (default: #66CDAA)</p>

</li>
<li><p>command &quot;Input.&quot; and &quot;Output.&quot; containers (default: silver)</p>

</li>
<li><p>command and event object arguments (default: pink)</p>

</li>
<li><p>command and event parameter arguments (default: #FFE4E1)</p>

</li>
</ul>

</dd>
<dt id="compare"><b>--compare</b></dt>
<dd>

<p>compares the two files that were specified on the command line, showing the changes made by the second one</p>

<p>note that this is identical to setting <b>--autobase</b> and <b>--showdiffs</b>; it also affects the behavior of <b>--lastonly</b></p>

</dd>
<dt id="components"><b>--components</b></dt>
<dd>

<p>affects only the <b>xml</b> report; generates a component for each object; if <b>--noobjects</b> is also specified, the component omits the object definition and consists only of parameter definitions</p>

</dd>
<dt id="configfile-s"><b>--configfile=s(&quot;&quot;)</b></dt>
<dd>

<p>the name of the configuration file; the configuration file format and usage are specific to the report type; not all report types use configuration files</p>

<p>the configuration file name can also be specified via <b>--option configfile=s</b> but this usage is deprecated</p>

<p>defaults to <b>report.ini</b> where <b>report</b> is the report type, e.g. <b>htmlbbf.ini</b> for the <b>htmlbbf</b> report</p>

</dd>
<dt id="cwmpindex-s-..-cwmp"><b>--cwmpindex=s(../cwmp)</b></dt>
<dd>

<p>affects only the <b>html</b> report; specifies the location of the BBF CWMP (or USP) index page, i.e. the page generated using the <b>htmlbbf</b> report; is used to generate a link back to the appropriate location within the index page</p>

<p>defaults to <b>../cwmp</b> (parent directory), which will work for the BBF web site but will not necessarily work in other locations; the generated link will be <b>cwmpindex#xmlfile</b>, e.g. <b>../cwmp#tr-069-1-0-0.xml</b></p>

</dd>
<dt id="cwmppath-s-cwmp"><b>--cwmppath=s(cwmp)</b></dt>
<dd>

<p>affects only the <b>htmlbbf</b> report; specifies the location of the XML and HTML files relative to the BBF CWMP index page</p>

<p>defaults to <b>cwmp</b> (sub-directory), which will work for the BBF web site; can be set to a URL such as <b>https://www.broadband-forum.org/cwmp</b> to generate a local BBF CWMP index page that references published content</p>

</dd>
<dt id="debugpath-p"><b>--debugpath=p(&quot;&quot;)</b></dt>
<dd>

<p>outputs debug information for parameters and objects whose path names match the specified pattern</p>

</dd>
<dt id="deletedeprecated"><b>--deletedeprecated</b></dt>
<dd>

<p>mark all deprecated or obsoleted items as deleted</p>

</dd>
<dt id="diffs"><b>--diffs</b></dt>
<dd>

<p>has the same affect as specifying both <b>--lastonly</b> (reports only items that were defined or last modified in the last XML file on the command line) and <b>--showdiffs</b> (visually indicates the differences)</p>

</dd>
<dt id="diffsext-s-diffs"><b>--diffsext=s(diffs)</b></dt>
<dd>

<p>how diffs files referenced by the <b>htmlbbf</b> report are named; for DM Instance <b>foo.xml</b>, the diffs file name is <b>foo-diffsext.html</b>; the default is <b>diffs</b>, i.e. the default file name is <b>foo-diffs.html</b></p>

<p>note: as an advanced feature, if this option is specified twice, the first value should be <b>last</b> and will be used for files known to be named <b>foo-last.html</b> on the BBF CWMP page, and the second value (typically <b>diffs</b>) will be used for all other files</p>

</dd>
<dt id="dtprofile-s"><b>--dtprofile=s</b>...</dt>
<dd>

<p>affects only the <b>xml</b> report; can be specified multiple times; defines profiles to be used to generate an example DT instance</p>

<p>for example, specify <b>Baseline</b> to select the latest version of the <b>Baseline</b> pofile, or <b>Baseline:1</b> to select the <b>Baseline:1</b> profile</p>

<p><b>base</b> and <b>extends</b> attributes are honored, so (for example), <b>Baseline:2</b> will automatically include <b>Baseline:1</b> requirements</p>

</dd>
<dt id="dtspec-s"><b>--dtspec=s</b></dt>
<dd>

<p>affects only the <b>xml</b> report; has an affect only when <b>--dtprofile</b> is also present; specifies the value of the top-level <b>spec</b> attribute in the generated DT instance; if not specified, the spec defaults to <b>urn:example-com:device-1-0-0</b></p>

</dd>
<dt id="dtuuid-s"><b>--dtuuid=s</b></dt>
<dd>

<p>affects only the <b>xml</b> report; has an affect only when <b>--dtprofile</b> is also present; specifies the value of the top-level <b>uuid</b> attribute in the generated DT instance (there is no &quot;uuid:&quot; prefix); if not specified, the UUID defaults to <b>00000000-0000-0000-0000-000000000000</b></p>

</dd>
<dt id="exitcode-s"><b>--exitcode=s</b></dt>
<dd>

<p>if specified with no value or with a value of &quot;errors&quot;, the exit code is minus the number of reported errors, which will typically be masked to 8 bits, e.g. 2 errors would result in an exit code of -2, which might become 254</p>

<p>if specified with a value of &quot;fatals&quot;, the exit code is minus the number of reported fatal errors (with the same proviso about masking to 8 bits);</p>

<p>if not specified, the exit code is zero regardless of the number of errors</p>

</dd>
<dt id="help"><b>--help</b></dt>
<dd>

<p>requests output of usage information</p>

</dd>
<dt id="ignore"><b>--ignore</b></dt>
<dd>

<p>specifies a pattern; data models whose names begin with the pattern will be ignored</p>

</dd>
<dt id="ignoreenableparameter"><b>--ignoreenableparameter</b></dt>
<dd>

<p>causes the <b>enableParameter</b> attribute to be ignored when generating unique key text for the HTML report</p>

<p>note: use of this option is appropriate when generating reports for data models that will be used with USP; the <b>--usp</b> option enables it automatically</p>

</dd>
<dt id="immutablenonfunctionalkeys"><b>--immutablenonfunctionalkeys</b></dt>
<dd>

<p>causes non-functional unique keys to be treated as immutable when generating unique key text for the HTML report</p>

<p>note: use of this option is appropriate when generating reports for data models that will be used with USP; the <b>--usp</b> option enables it automatically</p>

</dd>
<dt id="importsuffix-s"><b>--importsuffix=s(&quot;&quot;)</b></dt>
<dd>

<p>specifies a suffix which, if specified, will be appended (preceded by a hyphen) to the name part of any imported files in <b>xml</b> reports</p>

</dd>
<dt id="include-d"><b>--include=d</b>...</dt>
<dd>

<p>can be specified multiple times; specifies directories to search for files specified on the command line or imported by other files</p>

<ul>

<li><p>for files specified on the command line, the current directory is always searched first</p>

</li>
<li><p>for files imported by other files, the directory containing the first file is always searched first; <b>this behavior has changed; previously the current directory was always searched</b></p>

</li>
<li><p>no search is performed for files that already include directory names</p>

</li>
</ul>

</dd>
<dt id="info"><b>--info</b></dt>
<dd>

<p>outputs a single line showing the version and date</p>

<p>(<b>--version</b> outputs the same information)</p>

</dd>
<dt id="lastonly"><b>--lastonly</b></dt>
<dd>

<p>reports only on items that were defined or last modified in the specification corresponding to the last XML file on the command line (as determined by the last XML file&#39;s <b>spec</b> attribute)</p>

<p>if <b>--compare</b> is also specified, the &quot;last only&quot; criterion uses the file name rather than the spec (so the changes shown will always be those from the second file on the command line even if both files have the same spec)</p>

</dd>
<dt id="loglevel-tn-i"><b>--loglevel=tn(i)</b></dt>
<dd>

<p>sets the log level; this consists of a <b>type</b> and a <b>sublevel</b> (0-9); all messages up and including this sublevel will be output to <b>stderr</b>; the default type and sublevel are <b>warning</b> and <b>0</b>, which means that by default only error, informational and sublevel 0 warning messages will be output</p>

<p>by default, messages are output with a prefix consisting of the upper-case first letter of the log level type in parentheses, followed by a space; for example, &quot;(E) &quot; indicates an error message; the message prefix can be suppressed using <b>--nologprefix</b></p>

<p>the possible log level types, which can be abbreviated to a single character, are:</p>

<dl>

<dt id="fatal"><b>fatal</b></dt>
<dd>

<p>only fatal messages will be output; the sublevel is ignored</p>

</dd>
<dt id="error"><b>error</b></dt>
<dd>

<p>only fatal and error messages will be output; the sublevel is ignored</p>

</dd>
<dt id="info1"><b>info</b></dt>
<dd>

<p>only fatal, error and informational messages will be output; the sublevel is ignored</p>

</dd>
<dt id="warning"><b>warning</b></dt>
<dd>

<p>only fatal, error, informational and warning messages will be output; the sublevel distinguishes different levels of warning messages</p>

<p>currently only warning messages with sublevels 0, 1 and 2 are distinguished, but all values in the range 0-9 are valid</p>

</dd>
<dt id="debug"><b>debug</b></dt>
<dd>

<p>fatal, error, informational, warning and debug messages will be output; the sublevel distinguishes different levels of debug messages</p>

<p>currently only debug messages with sublevels 0, 1 and 2 are distinguished, but all values in the range 0-9 are valid</p>

</dd>
</dl>

<p>for example, a value of <b>d1</b> will cause fatal, error, informational, all warning, and sublevel 0 and 1 debug messages to be output</p>

<p>the log level feature is used to implement the functionality of <b>--quiet</b>, <b>--pedantic</b> and <b>--verbose</b> (all of which are still supported); these options are processed in the order (<b>loglevel</b>, <b>quiet</b>, <b>pedantic</b>, <b>verbose</b>), so (for example) <b>--loglevel=d --pedantic</b> is the same as <b>--loglevel=w</b></p>

<p>a log level of warning or debug also enables XML schema validation of DM instances; XML schemas are located using the <b>schemaLocation</b> attribute:</p>

<ul>

<li><p>if it specifies an absolute path, no search is performed</p>

</li>
<li><p>if it specifies a relative path, the directories specified via <b>--include</b> are searched</p>

</li>
<li><p>URLs are treated specially; if XML catalogs were supplied (see <b>--catalog</b>) then they govern the behavior; otherwise, the directory part is ignored and the schema is located as for a relative path (above)</p>

</li>
</ul>

</dd>
<dt id="logoalt-s-Broadband-Forum"><b>--logoalt=s(&quot;Broadband Forum&quot;)</b></dt>
<dd>

<p>alternative text for the logo image in the top left-hand corner of the HTML report</p>

<p>if any other <b>--logoxxx</b> options are specified, the default is an empty string</p>

</dd>
<dt id="logoref-s-https:-www.broadband-forum.org"><b>--logoref=s(&quot;https://www.broadband-forum.org/&quot;)</b></dt>
<dd>

<p>URL visited when the logo image in the top left-hand corner of the HTML report is clicked</p>

<p>if any other <b>--logoxxx</b> options are specified, the default is an empty string</p>

</dd>
<dt id="logosrc-s-https:-www.broadband-forum.org-images-logo-broadband-forum.gif"><b>--logosrc=s(&quot;https://www.broadband-forum.org/images/logo-broadband-forum.gif&quot;)</b></dt>
<dd>

<p>URL of logo image in the top left-hand corner of the HTML report</p>

<p>if any other <b>--logoxxx</b> options are specified, the default is an empty string</p>

</dd>
<dt id="markmounttype"><b>--markmounttype</b></dt>
<dd>

<p>mark mountable objects and mount point objects in color and text (only applicable for USP)</p>

<p>note: this option is only applicable to USP; the <b>--usp</b> option enables it automatically</p>

</dd>
<dt id="marktemplates"><b>--marktemplates</b></dt>
<dd>

<p>mark selected template expansions with <b>&amp;&amp;&amp;&amp;</b> followed by template-related information, a colon and a space</p>

<p>for example, the <b>reference</b> template is marked by a string such as <b>&amp;&amp;&amp;&amp;pathRef-strong:</b>, <b>&amp;&amp;&amp;&amp;pathRef-weak:</b>, <b>&amp;&amp;&amp;&amp;instanceRef-strong:</b>, <b>&amp;&amp;&amp;&amp;instanceRef-strong-list:</b> or <b>enumerationRef:</b></p>

<p>and the <b>list</b> template is marked by a string such as <b>&amp;&amp;&amp;&amp;list-unsignedInt:</b> or <b>&amp;&amp;&amp;&amp;list-IPAddress:</b></p>

</dd>
<dt id="maxchardiffs-i-5---maxworddiffs-i-10"><b>--maxchardiffs=i(5)</b>, <b>--maxworddiffs=i(10)</b></dt>
<dd>

<p>these control how differences are shown in descriptions; each paragraph is handled separately</p>

<ul>

<li><p>if the number of inserted and/or deleted characters in the paragraph is less than or equal to <b>maxchardiffs</b>, changes are shown at the character level</p>

</li>
<li><p>otherwise, if the number of inserted and/or deleted words in the paragraph is less than or equal to <b>maxworddiffs</b>, changes are shown at the word level</p>

</li>
<li><p>otherwise, the entire paragraph is shown as a single change</p>

</li>
</ul>

</dd>
<dt id="noautomodel"><b>--noautomodel</b></dt>
<dd>

<p>disables the auto-generation, if no <b>model</b> element was encountered, of an auto-generated model that references each non-internal component, i.e. each component whose name doesn&#39;t begin with an underscore</p>

<p>this is deprecated in favor of <b>--automodel</b> and will be removed in a future version (at which point the default behavior will be changed so an automatic model is not created)</p>

<p>it is better to use <b>--automodel</b> because it allows various error messages to be suppressed</p>

</dd>
<dt id="nocomments"><b>--nocomments</b></dt>
<dd>

<p>disables generation of XML comments showing what changed etc (<b>--verbose</b> always switches it off)</p>

</dd>
<dt id="nofontstyles"><b>--nofontstyles</b></dt>
<dd>

<p>disables use of font-related styles in the <b>html</b> and <b>htmlbbf</b> (index file) reports; this allows these styles to be inherited, e.g. from a theme</p>

<p>note: this option doesn&#39;t disable use of red / blue text for indicating deletions / insertions</p>

</dd>
<dt id="nohyphenate"><b>--nohyphenate</b></dt>
<dd>

<p>prevents automatic insertion of soft hyphens</p>

</dd>
<dt id="nolinks"><b>--nolinks</b></dt>
<dd>

<p>affects only the <b>html</b> report; disables generation of hyperlinks (which makes it easier to import HTML into Word documents)</p>

</dd>
<dt id="nologprefix"><b>--nologprefix</b></dt>
<dd>

<p>suppresses log message prefixes, i.e. the strings such as &quot;E: &quot; or &quot;W: &quot; that indicate errors, warnings etc</p>

</dd>
<dt id="nomodels"><b>--nomodels</b></dt>
<dd>

<p>specifies that model definitions should not be reported</p>

</dd>
<dt id="noobjects"><b>--noobjects</b></dt>
<dd>

<p>affects only the <b>xml</b> report when <b>--components</b> is specified; omits objects from component definitions</p>

</dd>
<dt id="noparameters"><b>--noparameters</b></dt>
<dd>

<p>affects only the <b>xml</b> report when <b>--components</b> is specified; omits parameters from component definitions</p>

<p><b>NOT YET IMPLEMENTED</b></p>

</dd>
<dt id="noprofiles"><b>--noprofiles</b></dt>
<dd>

<p>specifies that profile definitions should not be reported</p>

</dd>
<dt id="noshowreadonly"><b>--noshowreadonly</b></dt>
<dd>

<p>disables showing read-only enumeration and pattern values as <b>READONLY</b></p>

</dd>
<dt id="notemplates"><b>--notemplates</b></dt>
<dd>

<p>suppresses template expansion (currently affects only <b>html</b> reports</p>

</dd>
<dt id="nowarnbibref"><b>--nowarnbibref</b></dt>
<dd>

<p>disables bibliographic reference warnings</p>

<p>see also <b>--warnbibref</b></p>

</dd>
<dt id="nowarnenableparameter"><b>--nowarnenableparameter</b></dt>
<dd>

<p>disables warnings when a writable table has no enable parameter</p>

</dd>
<dt id="nowarnnumentries"><b>--nowarnnumentries</b></dt>
<dd>

<p>disables warnings (and/or errors) when a multi-instance object has no associated NumberOfEntries parameter</p>

<p>this is always an error so disabling these warnings isn&#39;t such a good idea</p>

</dd>
<dt id="nowarnredef"><b>--nowarnredef</b></dt>
<dd>

<p>disables parameter and object redefinition warnings (these warnings are also output if <b>--verbose</b> is specified)</p>

<p>there are some circumstances under which parameter or object redefinition is not worthy of comment</p>

</dd>
<dt id="nowarnreport"><b>--nowarnreport</b></dt>
<dd>

<p>disables the inclusion of error and warning messages in reports (currently only in <b>HTML</b> reports)</p>

</dd>
<dt id="nowarnprofbadref"><b>--nowarnprofbadref</b></dt>
<dd>

<p>disables warnings when a profile references an invalid object or parameter</p>

<p>there are some circumstances under which it&#39;s useful to use an existing profile definition where some objects or parameters that it references have been (deliberately) deleted</p>

<p>this is deprecated because it is no longer needed (use status=&quot;deleted&quot; as appropriate to suppress such errors)</p>

</dd>
<dt id="nowarnstaticdefault"><b>--nowarnstaticdefault</b></dt>
<dd>

<p>disables &quot;parameter within static object has a default value&quot; warnings</p>

</dd>
<dt id="nowarnuniquekeys"><b>--nowarnuniquekeys</b></dt>
<dd>

<p>disables warnings when a multi-instance object has no unique keys</p>

</dd>
<dt id="nowarnwtref"><b>--nowarnwtref</b></dt>
<dd>

<p>disables &quot;referenced file&#39;s spec indicates that it&#39;s still a WT&quot; warnings</p>

</dd>
<dt id="noxmllink"><b>--noxmllink</b></dt>
<dd>

<p>disables inclusion (in <b>html</b> reports) of links back to the appropriate place in the <b>htmlbbf</b> report (index page)</p>

</dd>
<dt id="objpat-p"><b>--objpat=p</b></dt>
<dd>

<p>specifies an object name pattern (a regular expression); objects that do not match this pattern will be ignored (the default of &quot;&quot; matches all objects)</p>

</dd>
<dt id="option-n-v"><b>--option=n=v</b>...</dt>
<dd>

<p>can be specified multiple times; defines options that can be accessed and used when generating the report; useful when used with reports implemented in plugins</p>

<p>see <b>--report</b> for details of options supported by standard report types</p>

</dd>
<dt id="outfile-s"><b>--outfile=s</b></dt>
<dd>

<p>specifies the output file; if not specified, output will be sent to <i>stdout</i></p>

<p>if the file already exists, it will be quietly overwritten</p>

<p>the only reason to use this option (rather than using shell output redirection) is that it allows the tool to know the name of the output file and therefore to include it in the generated XML, HTML report etc</p>

</dd>
<dt id="pedantic-i-1"><b>--pedantic=[i(1)]</b></dt>
<dd>

<p>enables output of warnings to <i>stderr</i> when logical inconsistencies in the XML are detected; if the option is specified without a value, the value defaults to 1</p>

<p>this has the same effect as setting <b>--loglevel</b> to &quot;w&quot; (warning) followed by the pedantic value minus one, e.g. &quot;w1&quot; for <b>--pedantic=2</b></p>

</dd>
<dt id="plugindir-d"><b>--plugindir=d</b>...</dt>
<dd>

<p>can be specified multiple times; specifies directories to search for plugins; defaults to the <b>--include</b> directories</p>

<p>all <b>--plugindir</b> subdirectories are also searched for plugins</p>

</dd>
<dt id="plugin-s"><b>--plugin=s</b>...</dt>
<dd>

<p>can be specified multiple times; defines external plugins that can define additional report types</p>

<p>plugins are searched for in the <b>--plugindir</b> directories (and their subdirectories)</p>

<ul>

<li><p>currently each plugin must correspond to a file of the same name but with a <b>.pm</b> (Perl Module) extension; for example, <b>--plugin=foo</b> must correspond to a file called <b>foo.pm</b>; the directories specified via the Perl include path (including the current directory) and via <b>--include</b> are searched</p>

</li>
<li><p>each plugin must define a package of the same name and can define one of more routines with names of the form <b>rrr_node</b>; <b>rrr</b> becomes an additional report type; if only one such routine is defined then by convention <b>rrr</b> should be the same as the plugin name; for example, <b>foo.pm</b> will always define the <b>foo</b> package and will usually define a <b>foo_node</b> routine</p>

</li>
<li><p>the file can optionally also define routines with names of the form <b>rrr_init</b>, <b>rrr_begin</b>, <b>rrr_postpar</b>, <b>rrr_post</b> and <b>rrr_end</b></p>

</li>
<li><p><b>rrr_init</b> is called after processing command line arguments but before reading any of the DM files; it can be used for initializing the plugin, e.g. parsing configuration files</p>

</li>
<li><p>each of the other routines is called with three arguments; the first is the node on which it is to report; the second is the indentation level (0 means the initial call, for which the node is the root node, i.e. the parent of any <b>model</b> nodes); the third is a reference to an option hash</p>

</li>
<li><p>the <b>begin</b> routine is called at the beginning; the <b>node</b> routine is called for each node; the <b>postpar</b> routine (if defined) is called after parameter <b>node</b> routines have been called; the <b>post</b> routine (if defined) is called after child node <b>node</b> routines have been called; the <b>end</b> routine is called at the end; these routines are not themselves responsible for traversing child nodes</p>

</li>
<li><p>the node object is a reference to a hash that contains keys such as <b>path</b> and <b>name</b>; it is not currently documented</p>

</li>
<li><p>it is safe to store information on the node; any new names should begin <b>rrr_</b> in order to avoid name clashes</p>

</li>
<li><p>these instructions are not expected to be sufficient to write a plugin; it will be necessary to consult the main report tool source code; the plugin interface may change in the future, in which case plugins may need to be adjusted</p>

</li>
<li><p>the following illustrates just about the simplest possible valid plugin; it would be placed in a file called <b>foo.pm</b> and would be used by specifying <b>--plugin=foo --report=foo</b></p>

<pre><code> package foo;

 sub foo_node
 {
     my ($node) = @_;
     print &quot;$node-&gt;{path}\n&quot;;
 }

 1;</code></pre>

</li>
</ul>

</dd>
<dt id="quiet"><b>--quiet</b></dt>
<dd>

<p>suppresses informational messages</p>

<p>this used to have the same effect as setting <b>--loglevel</b> to &quot;e&quot; (error) but now it simply suppresses such messages</p>

</dd>
<dt id="report-html-htmlbbf-null-tab-text-xls-xml-xsd-other"><b>--report=html|htmlbbf|(null)|tab|text|xls|xml|xsd|other...</b></dt>
<dd>

<p>specifies the report format; one of the following:</p>

<dl>

<dt id="html"><b>html</b></dt>
<dd>

<p>HTML document; see also <b>--nolinks</b> and <b>--notemplates</b></p>

</dd>
<dt id="htmlbbf"><b>htmlbbf</b></dt>
<dd>

<p>HTML document containing the information in the BBF CWMP (or USP) index page; when generating this report, all the XSD and XML files are specified on the command line</p>

<p>the <b>htmlbbf</b> report reads a configuration file whose name can be specified using <b>--configfile</b></p>

<p>the <b>htmlbbf</b> report supports the following <b>options</b>:</p>

<dl>

<dt id="htmlbbf_configfile_suffix-SUFFIX"><b>htmlbbf_configfile_suffix=SUFFIX</b></dt>
<dd>

<p>causes use of config file field name FIELD-SUFFIX rather than FIELD (the default); e.g. a value of &quot;usp&quot; means that the title will be taken from &quot;title-usp&quot; rather than &quot;title&quot;</p>

</dd>
<dt id="htmlbbf_createfragment-VALUE"><b>htmlbbf_createfragment=VALUE</b></dt>
<dd>

<p>causes generation of a fragment of HTML, suitable for inclusion in an HTML document (the option value is ignored, but should be &quot;true&quot;)</p>

</dd>
<dt id="htmlbbf_deprecatedmodels-MODELS"><b>htmlbbf_deprecatedmodels=MODELS</b></dt>
<dd>

<p>causes the specified data models to be marked as deprecated (the option value is a space-separated list of model names and major versions, e.g. &quot;InternetGatewayDevice:1 Device:1&quot;)</p>

<p>it may be possible (although less convenient) to achieve the same effect with <b>--htmlbbf_deprecatedpattern</b></p>

</dd>
<dt id="htmlbbf_deprecatedpattern-PATTERN"><b>htmlbbf_deprecatedpattern=PATTERN</b></dt>
<dd>

<p>causes any files whose names match the pattern to be marked as deprecated</p>

</dd>
<dt id="htmlbbf_omitcommonxml-VALUE"><b>htmlbbf_omitcommonxml=VALUE</b></dt>
<dd>

<p>causes any XML files whose names end with <b>-common.xml</b> to be ignored (the option value is ignored, but should be &quot;true&quot;)</p>

<p>deprecated because the same effect can be achieved with <b>--htmlbbf_omitpattern</b> and a pattern of &quot;-common\.xml$&quot;</p>

</dd>
<dt id="htmlbbf_omitpattern-PATTERN"><b>htmlbbf_omitpattern=PATTERN</b></dt>
<dd>

<p>causes any files whose names match the specified pattern to be ignored</p>

</dd>
<dt id="htmlbbf_onlyfullxml-VALUE"><b>htmlbbf_onlyfullxml=VALUE</b></dt>
<dd>

<p>causes only full XML to be included; affects only data model XML, not component or support XML (the option value is ignored, but should be &quot;true&quot;)</p>

</dd>
<dt id="htmlbbf_protobufurlprefix-VALUE"><b>htmlbbf_protobufurlprefix=VALUE</b></dt>
<dd>

<p>the URL prefix to be used when generating URLs for protobuf schemas; defaults to <b>--cwmppath</b></p>

</dd>
</dl>

<p>see OD-290 and OD-148 for more details</p>

</dd>
<dt id="null"><b>null</b></dt>
<dd>

<p>no output; errors go to <i>stdout</i> rather than <i>stderr</i> (default)</p>

</dd>
<dt id="tab"><b>tab</b></dt>
<dd>

<p>tab-separated list, one object or parameter per line</p>

</dd>
<dt id="text"><b>text</b></dt>
<dd>

<p>indented text</p>

</dd>
<dt id="xls"><b>xls</b></dt>
<dd>

<p>Excel XML spreadsheet</p>

</dd>
<dt id="xml"><b>xml</b></dt>
<dd>

<p>if <b>--lastonly</b> is specified, DM XML containing only the changes made by the final file on the command line; see also <b>--autobase</b></p>

<p>if <b>--lastonly</b> is not specified, DM XML with all imports resolved (apart from bibliographic references and data type definitions); use <b>--dtprofile</b>, optionally with <b>--dtspec</b> and <b>--dtuuid</b>, to generate DT XML for the specified profiles; use <b>--canonical</b> to omit transient information, e.g. dates and times, that makes it harder to compare reports; use <b>--components</b> (perhaps with <b>--noobjects</b> or <b>--noparameters</b>) to generate component definitions</p>

</dd>
<dt id="xml2"><b>xml2</b></dt>
<dd>

<p>same as the <b>xml</b> report with <b>--lastonly</b> not specified; deprecated (use <b>xml</b> instead)</p>

</dd>
<dt id="xsd"><b>xsd</b></dt>
<dd>

<p>W3C schema</p>

</dd>
<dt id="other">other...</dt>
<dd>

<p>other report types can be supported via <b>--plugin</b></p>

</dd>
</dl>

</dd>
<dt id="showdiffs"><b>--showdiffs</b></dt>
<dd>

<p>currently affects only the <b>text</b> and <b>html</b> reports; visually indicates the differences resulting from the last XML file on the command line</p>

<p>for the <b>html</b> report, insertions are shown in blue and deletions are shown in red strikeout; in order to enhance readability, hyperlinks are not shown in a special color (but are still underlined); note that this hyperlink behavior uses <b>color=inherit</b>, which apparently isn&#39;t supported by Internet Explorer</p>

<p>is implied by <b>--compare</b></p>

</dd>
<dt id="showreadonly"><b>--showreadonly</b></dt>
<dd>

<p>shows read-only enumeration and pattern values as <b>READONLY</b>; this is enabled by default but can be disabled using <b>--noshowreadonly</b></p>

<p>this is deprecated because it is enabled by default and therefore has no effect</p>

</dd>
<dt id="showspec"><b>--showspec</b></dt>
<dd>

<p>currently affects only the <b>html</b> report; generates a <b>Spec</b> rather than a <b>Version</b> column</p>

</dd>
<dt id="showsyntax"><b>--showsyntax</b></dt>
<dd>

<p>adds an extra column containing a summary of the parameter syntax; is like the Type column for simple types, but includes additional details for lists</p>

</dd>
<dt id="showunion"><b>--showunion</b></dt>
<dd>

<p>adds &quot;This object is a member of a union&quot; text to objects that have &quot;1 of n&quot; or &quot;union&quot; semantics; such objects are identified by having <b>minEntries=0</b> and <b>maxEntries=1</b></p>

</dd>
<dt id="sortobjects"><b>--sortobjects</b></dt>
<dd>

<p>currently affects only the <b>html</b> report; reports objects (and profiles) in alphabetical order rather than in the order that they are defined in the XML</p>

</dd>
<dt id="special-deprecated-imports-key-nonascii-normative-notify-obsoleted-pathref-profile-ref-rfc"><b>--special=deprecated|imports|key|nonascii|normative|notify|obsoleted|pathref|profile|ref|rfc</b></dt>
<dd>

<p>performs special checks, most of which assume that several versions of the same data model have been supplied on the command line, and many of which operate only on the highest version of the data model</p>

<dl>

<dt id="deprecated-obsoleted"><b>deprecated</b>, <b>obsoleted</b></dt>
<dd>

<p>for each profile item (object or parameter) report if it is deprecated or obsoleted</p>

</dd>
<dt id="imports-imports:element-imports:element:name"><b>imports</b>, <b>imports:element</b>, <b>imports:element:name</b></dt>
<dd>

<p>lists the components, data types and models that are defined in all the files that were read by the tool</p>

<p><b>element</b> is <b>component</b>, <b>dataType</b> or <b>model</b> and can be abbreviated, so it is usual to specify just the first letter</p>

<p><b>name</b> is the first part of the element name (it can be the full element name but this is not necessary); element names which start with an underscore will also be listed</p>

<p>the output format is illustrated by these examples:</p>

<pre><code> report.pl --special=imports:m:Device:2 tr-181-2-3-0.xml
 model {tr-181-2-3-0}Device:2.3
 model {tr-181-2-3-0}Device:2.2 = {tr-181-2-2-0}Device:2.2
 model {tr-181-2-2-0}Device:2.2
 model {tr-181-2-2-0}Device:2.1 = {tr-181-2-1-0}Device:2.1
 model {tr-181-2-1-0}Device:2.1
 model {tr-181-2-1-0}Device:2.0 = {tr-181-2-0-1}Device:2.0
 model {tr-181-2-0-1}Device:2.0

 report.pl --special=imports:c:UPnP tr-181-2-3-0.xml
 component {tr-157-1-3-0}UPnP = {tr-157-1-2-0}UPnP
 component {tr-157-1-2-0}UPnPDiffs
 component {tr-157-1-2-0}UPnP
 component {tr-157-1-2-0}_UPnP = {tr-157-1-1-0}UPnP {tr-157-1-0-0}
 component {tr-157-1-1-0}UPnP = {tr-157-1-0-0}UPnP
 component {tr-157-1-0-0}UPnP
 component {tr-181-2-0-1}UPnP = {tr-157-1-2-0}UPnP
 component {tr-157-1-4-0}UPnP = {tr-157-1-3-0}UPnP {tr-157-1-2-0}</code></pre>

<p>each line starts with the element name, followed by the element in the form <b>{file}name</b>; then, if the element is imported from another file (possibly using a different name), that is indicated after an equals sign; finally if the actual definition is in a different file, that is indicated in the form <b>{file}</b></p>

<p>for example, the following line indicates that the <b>tr-157-1-2-0</b> <b>_UPnP</b> component is imported from the <b>tr-157-1-1-0</b> <b>UPnP</b> component, which is actually defined in <b>tr-157-1-0-0</b></p>

<pre><code> component {tr-157-1-2-0}_UPnP = {tr-157-1-1-0}UPnP {tr-157-1-0-0}</code></pre>

</dd>
<dt id="key"><b>key</b></dt>
<dd>

<p>for each table with a functional key, report access, path and the key</p>

</dd>
<dt id="nonascii"><b>nonascii</b></dt>
<dd>

<p>check which model, object, parameter or profile descriptions contain characters other than ASCII 9-10 or 32-126; the output is the full path names of all such items, together with the offending descriptions with the invalid characters surrounded by pairs of asterisks</p>

<p>the above list is followed by a list of the invalid characters and how often each one occurred</p>

</dd>
<dt id="normative"><b>normative</b></dt>
<dd>

<p>check which model, object, parameter or profile descriptions contain inappropriate use of normative language, i.e. lower-case normative words, or <b>MAY NOT</b>; the output is the full path names of all such items, together with the offending descriptions with the normative words surrounded by pairs of asterisks</p>

<p>the above list is followed by a list of the invalid terms and how often each one occurred</p>

</dd>
<dt id="notify"><b>notify</b></dt>
<dd>

<p>check which parameters in the highest version of the data model are not in the &quot;can deny active notify request&quot; table; the output is the full path names of all such parameters, one per line</p>

</dd>
<dt id="pathref"><b>pathref</b></dt>
<dd>

<p>for each pathRef parameter, report cases where a &quot;Agent-managed, non-fixed&quot; object references another &quot;Agent-managed, non-fixed&quot; object; these are candidate cases for objects that should have the same lifetime</p>

</dd>
<dt id="profile"><b>profile</b></dt>
<dd>

<p>check which parameters defined in the highest version of the data model are not in profiles; the output is the full path names of all such parameters, one per line</p>

</dd>
<dt id="rfc"><b>rfc</b></dt>
<dd>

<p>check which model, object, parameter or profile descriptions mention RFCs without giving references; the output is the full path names of all such items, together with the offending descriptions with the normative words surrounded by pairs of asterisks</p>

<p>this doesn&#39;t work very well and isn&#39;t particularly useful</p>

</dd>
<dt id="ref"><b>ref</b></dt>
<dd>

<p>for each reference parameter, report access, reference type and path</p>

</dd>
</dl>

</dd>
<dt id="thisonly"><b>--thisonly</b></dt>
<dd>

<p>outputs only definitions defined in the files on the command line, not those from imported files</p>

</dd>
<dt id="tr106-s-TR-106"><b>--tr106=s(TR-106)</b></dt>
<dd>

<p>indicates the TR-106 version (i.e. the <b>bibref</b> name) to be referenced in any automatically generated description text</p>

<p>the default value is the latest version of TR-106 that is referenced elsewhere in the data model (or <b>TR-106</b> if it is not referenced elsewhere)</p>

</dd>
<dt id="trpage-s-https:-www.broadband-forum.org-technical-download"><b>--trpage=s(https://www.broadband-forum.org/technical/download/)</b></dt>
<dd>

<p>indicates the location of the PDF versions of BBF standards; is concatenated with the filename (trailing slash is added if necessary)</p>

</dd>
<dt id="ucprofile-s"><b>--ucprofile=s</b>...</dt>
<dd>

<p>affects only the <b>xml</b> report; can be specified multiple times; defines use case profiles whose requirements will be checked against the <b>--dtprofile</b> profiles</p>

</dd>
<dt id="ugly"><b>--ugly</b></dt>
<dd>

<p>disables some prettifications, e.g. inserting spaces to encourage line breaks</p>

<p>this is deprecated because it has been replaced with the more specific <b>--nohyphenate</b> and <b>--showsyntax</b></p>

</dd>
<dt id="upnpdm"><b>--upnpdm</b></dt>
<dd>

<p>transforms output (currently HTML only) so it looks like a <b>UPnP DM</b> (Device Management) data model definition</p>

</dd>
<dt id="usp"><b>--usp</b></dt>
<dd>

<p>specifies that the file is intended for use with USP and automatically enables the corresponding options, namely:</p>

<ul>

<li><p><b>altnotifreqstyle</b></p>

</li>
<li><p><b>clampversion=2.12</b></p>

</li>
<li><p><b>ignoreenableparameter</b></p>

</li>
<li><p><b>immutablenonfunctionalkeys</b></p>

</li>
<li><p><b>markmounttype</b></p>

</li>
</ul>

<p>if the file &quot;looks like&quot; a USP file, e.g., it ends <b>-usp.xml</b> or <b>-usp-full.xml</b>, then this option is set automatically</p>

</dd>
<dt id="verbose-i-1"><b>--verbose[=i(1)]</b></dt>
<dd>

<p>enables verbose output; the higher the level the more the output</p>

<p>this has the same effect as setting <b>--loglevel</b> to &quot;d&quot; (debug) followed by the verbose value minus one, e.g. &quot;d2&quot; for <b>--verbose=3</b></p>

</dd>
<dt id="version"><b>--version</b></dt>
<dd>

<p>outputs a single line showing the version and date</p>

<p>(<b>--info</b> now outputs the same information)</p>

</dd>
<dt id="warnbibref-i-1"><b>--warnbibref[=i(1)]</b></dt>
<dd>

<p>enables bibliographic reference warnings (these warnings are also output if <b>--verbose</b> is specified); the higher the level the more warnings</p>

<p>setting it to -1 is the same as setting <b>--nowarnbibref</b> and suppresses various bibref-related errors that would normally be output</p>

</dd>
<dt id="writonly"><b>--writonly</b></dt>
<dd>

<p>reports only on writable parameters (should, but does not, suppress reports of read-only objects that contain no writable parameters)</p>

</dd>
<dt id="xmllinelength-i-79"><b>--xmllinelength=i(79)</b></dt>
<dd>

<p>affects only the <b>xml</b> report and cwmp-datamodel-report (dmr) versions 1.0 or higher</p>

<p>sets the maximum line length when wrapping descriptions and other multi-line text such as templates (long words won&#39;t be split, so lines can be longer)</p>

<p>setting it to 0 disables wrapping</p>

</dd>
</dl>

<h1 id="LIMITATIONS">LIMITATIONS</h1>

<p>This script is only for illustration of concepts and has many shortcomings.</p>


</body>

</html>


